This is a documentation of the changes to the SWI interface to FileSwitch
made between Risc OS 2.00 and 2.05.

Changes to old SWIs.
--------------------

There have been few changes made to old SWIs. Mostly they are bug fixes and
slight functionality changes necessary to support MultiFS.

*  Path variables now work properly.

*  Write operations accept wildcards.

*  A new object type is added, the file-and-directory object type:
        Object type     Meaning
        0               Object not present - neither file nor directory
                        specific operations will work on this.
        1               Object is a file - file operations only will work on
                        this.
        2               Object is a directory - directory operations only
                        will work on this.
        3               Object is both a file and a directory - both file
                        and directory operations will work when applied to
                        this.

*  FileSwitch now handles absolute directories which means that some old
        interfaces are impossible to support properly. The interfaces which
        don't work as well as they used to are:
        OS_GBPB  5  Read name and boot (*Opt 4) option of disc - this now
                        always returns 'Unset'.
        OS_GBPB  6  Read current directory name and privilege byte - this
                        will now always return the realtionship to the
                        current directory as 'owner'. This should not be a
                        problem as your program should check for errors ON
                        ALL OPERATIONS anyway!
        OS_GBPB  7  Read library directory name and privilege byte - has the
                        same change as OS_GBPB 6.

*  OS_GenerateError no longer checks the filename passed to it.

*  OS_FSControl  13  Check for presence of a filing system - this still
        returns a pointer to the filing system control block in r2, but the
        contents of that block have changed - and they're still not going to
        be documented externally to FileSwitch!

*  Some of the interfaces which filing systems were expected to support are
        no longer used. These are:
        *  FSEntry_Open with r0=1, create and open for update. A file is now
                created then opened using FSEntry_Open with r0=2 open for
                update. If, however, the filing system returns an error in
                the create operation, then FileSwitch will resort to
                FSEntry_Open with r0=1, create and open for update.
        *  FSEntry_File with r0=2, 3 or 4 Write load address, execution
                address and attributes. This are now replaced by
                FSEntry_File with r0=1 Write catalogue information calls.
        *  FSEntry_File with r0=9 read catalogue information (no length) is
                no longer used. It was only ever used by OS_FSControl 26
                copy objects.
        *  FSEntry_Func with r0=0 or 1 are no longer used as FileSwitch now
                manages @, %, & and \.
        *  FSEntry_Func with r0=2, 3, 4, 5, 6, 9, 20 are no longer used -
                FileSwitch now performs these 'by hand'.
        *  FSEntry_Func with r0=11, 12 and 13 are no longer used as
                FileSwitch attempts to emulate them as best it can.
        *  FSEntry_Func with r0=18 wasn't accessible via documented
                interfaces, and won't ever be, so it is now redundent.
        *  Filing systems no longer need to maintain @, &, \ and % as
                FileSwitch now does this. There is an option to force
                references to & and % through. Parents (^) are now sorted
                out by FileSwitch before handing a path through to the
                filing system.

*  When registering a filing system with FileSwitch (OS_FSControl 12) there
        are some new bits in the filing system information word:

        Bit New Meaning if set
        31      special fields are supported
        30      Streams are interactive
        29      Filing system supports null-length filenames
        28      Call the filing system for openning whether the file exists or not
        27      Inform the filing system of flushes using FSEntry_Args 255
        26   x  Filing system supports FSEntry_File 9 (read info, no length)
        25      Filing system supports FSEntry_Func 20 (*FileInfo)
        24   x  Filing system supports FSEntry_Func 18 (set contexts)
        23   *  Filing system supports MultiFS extensions
        22   *  Give the filing system & and % in paths when appropriate
        21   *  Don't bother storing directories for this filing system
        20   *  Don't use fsfile_Load, but use openin, GBPB, close instead
        19   *  Don't use fsfile_Save, but use create, openup, GBPB, close instead
        18   *  Use FSEntry_Func 9 (access objects) in preference to OS_Files
        17   *  Extra info field is present in the filing system information block
        16   *  Filing system is read-only
        15-8    Minimum number of files openable at once
        7-0     Filing system number

        * - Introduced in Risc OS 2.5
        x - Not used in Risc OS 2.5

        When bit 17 is set (extra info present) the filing system
        information block is extended with an extra information word. This
        means the information block has this format:

        Offset  Contents
        &00     filing system name
        &04     Startup text
        &08     open
        &0c     getbytes
        &10     putbytes
        &14     args
        &18     close
        &1c     file
        &20     information word
        &24     func
        &28     gbpb
        &2c     extra information word

        If the extra information word is absent, then FileSwitch will assume
        its value is 0. The meanings of the extra information word bits are
        as follows:

        Bit     Meaning when set
        0       Filing system supports FSEntry_Func 34
        1       Filing system should be called to do Cat
        2       Filing system should be called to do Ex
        3-31    reserved for future use and should be set to 0

        Bits 1 and 2 of the extra info should only be set if the filing
        system provides a non-standard display for Cat and Ex respectively.

        FSEntry_Func 34 (fsfunc_DirIs)

        In      r1 = pointer to nul-terminated directory name
                r2 = which directory
                r6 = pointer to special field

        Out     registers preserved

        This call is provided so that filing systems can optimise their handling of
        directory cahes. It will be made when FileSwitch has successfully changed a
        directory, which one being determined by r2:0-CSD,1-PSD,2-URD,3-Lib. A
        filing system should not change this directory on receiving this call
        (indeed, it is envisaged that a filing system would not have these
        directories stored as such), instead the filing system should use this
        information to help it decide which directories to cache and which to not.

        The MultiFS extensions are:
        FSEntry_Func 23 CanoncaliseSpecialAndDisc
        In      r1 = Special field or 0 if not present
                r2 = disc name or 0 if not present
                r3 = memory to fill special field in or 0 if just return length
                r4 = memory to fill disc name in or 0 if just return length
                r5 = length of special field memory block
                r6 = length of disc name memory block
        Out     r1 = pointer to canonical special field or 0 if not present
                r2 = pointer to canonical disc name or 0 if not present
                r3 = length of overflow from block or special field length
                r4 = length of overflow from block or disc name length
                r5 = unchanged
                r6 = unchanged
        Convert given special field and disc name to canonical (unique) forms. If no blocks
        passed in, fill in the overflow values anyway - this gives FileSwitch a
        means of finding the required storage for the values. The filled in strings
        should be 0 terminated.

        To explain: FileSwitch will make use of this call to convert the special
        field and disc name the user supplied into a canonical (unique) form.
        Typically, FileSwitch will call this to tidy up the file name given by the
        user into a canonical form. There are bascially two ways in which this will
        be called: to find out how much space is needed for the canonical versions
        of the disc and special fields; to do the conversion. These two calls will
        usually be made in close succession. For example, if the user specified a
        file as NetFS#Arf:&.thing.whatsit, FileSwitch will make this call as
        follows:
        r1 = pointer to the string "Arf" (nul terminated)
        r2 = 0
        r3 = 0
        r4 = 0
        r5 = some value of no importance as r3 is 0
        r6 = some value of no importance as r4 is 0
        NetFS will return these values:
        r1 = pointer to canonicalised special field (actually any non-0 value will
        do!)
        r2 = pointer to canonicalised disc name (as above, any non-0 value will do)
        r3 = length of the canonicalised special field (excluding any terminating
        nul)
        r4 = length of can0nicalised disc name (excluding any terminating nul)
        r5 = unchanged
        r6 = unchanged
        FileSwitch would be expected to now allocate memory for the strings of
        length specified by NetFS in the r3 and r4 return values, then call NetFS
        again as follows:
        r1 = pointer to the string "Arf"
        r2 = 0
        r3 = pointer to a buffer of length r5 bytes
        r4 = pointer to a buffer of length r6 bytes
        r5 = length of buffer pointed to by r3
        r6 = length of buffer pointed to by r4
        NetFS now fills in the buffers, (r3,r5) with the special field, (r4,r6) with
        the disc name, and returns:
        r1 = r3 in (buffer filled with "49.254")
        r2 = r4 in (buffer filled in with "Arf")
        r3 = 0 (no overflow over the end of the buffer)
        r4 = 0 (no overflow over the end of the buffer)
        r5 = unchanged
        r6 = unchanged

        FSEntry_Func 24 ResolveWildcard
        In      r1 = Path to a directory
                r2 = Address of block to place name, or 0 if none
                r3 = wildcarded object name
                r5 = size of block
                r6 = Special field
        Out     r1 = unchanged
                r2 = -1 if not found, or pointer to filled in name, or 0 if no block
        passed in.
                r3 = unchanged
                r4 = overflow of block, 0 if no overflow, -1 if FileSwitch should
        resolve this wildcard itself
                r5 = unchanged
        This call should find which object in the given directory matches the name
        given. If the filing system can not do a more efficient job than FileSwitch
        would if it were to use fsentry_func 14 and then to find which was the first
        match, then it should return with r4 = -1.

        FSEntry_File 10 (fsfile_ReadBlockSize)

        On entry
         r0 = 10
         r1 = file name
         r6 = special field

        On exit
         r2 = natural block size of the file (in bytes)
         r3-r5 may be corrupted

        FSEntry_Func 25 (fsfunc_DefectList)

        On entry
         r0 = 25
         r1 = pointer to nul-terminated name of image
         r2 = start of buffer in memory
         r5 = buffer length
         r6 = special field

        On exit
         r0-r6 unchanged

        This entry will fill the supplied buffer with the byte offsets to the start of
        the defects. The list will be terminated by a &20000000 value. It is
        an error for the specified image to not be the root object in an
        image (eg it is an error to map out a defect from
        adfs::HardDisc4.$.fred, but not an error from mapping it out from
        adfs::HardDisc4.$).

        FSEntry_Func 26 (fsfunc_AddDefect)

        On entry
         r0 = 26
         r1 = pointer to nul-terminate name of image
         r2 = byte offset to start of defect
         r6 = special field

        On exit
         r0-r2,r6 preserved

        This SWI will map out the specified defect from the specified image.
        It is an error for the specified image to not be the root object in
        an image (eg it is an error to map out a defect from
        adfs::HardDisc4.$.fred, but not an error from mapping it out from
        adfs::HardDisc4.$). If the defect cannot be mapped out then an error
        should be returned.

        FSEntry_Func 27 (fsfunc_ReadBootOption)

        On entry
         r0 = 27
         r1 = pointer to nul-terminated name of object on thing whose boot option is to be read
         r6 = special field

        On exit
         r0-r1,r6 preserved
         r2 = boot option (as in *Opt4,n)

        FSEntry_Func 28 (fsfunc_WriteBootOption)

        On entry
         r0 = 28
         r1 = pointer to nul-terminated name of object on thing whose boot option is to be written
         r2 = new boot option
         r6 = special field

        On exit
         r0-r2,r6 preserved

        FSEntry_Func 29 (fsfunc_UsedSpaceMap)

        On entry
         r0 = 29
         r1 = pointer to nul-terminated name of an object on the disc to have its used space map gotten
         r2 = buffer for map (pre-filled with 0s)
         r5 = size of buffer
         r6 = special field

        On exit
         regs preserved

        Fill in 1s in the used space map for parts of the disc which are
        neither free space nor bad block areas. In other words the buffer
        should end up with 1s where there are used parts of the disc. Each
        bit in the buffer corresponds with a BlockSize unit of the disc.

        FSEntry_Func 30 (fsfunc_ReadFreeSpace)

        On entry
         r0 = 30
         r1 = pointer to nul-terminated name of an object on the disc to have its free space gotten
         r6 = special field

        On exit
          r0 = free space
          r1 = biggest object creatable
          r2 = disc size

        Does the obvious.

        FSEntry_Func 31 (fsfunc_NameDisc)

        On entry
         r0 = 31
         r1 = pointer to nul-terminated name of an object on the disc to have its name changed
         r2 = new name of disc (nul-terminated)
         r6 = special field

        On exit
          regs preserved

        Does the obvious 

        FSEntry_Func 32 (fsfunc_StampImage)

        On entry
         r0 = 32
         r1 = pointer to nul-terminated name of an object on the disc to be stamped
         r2 = type of image stamping to take place
         r6 = special field

        On exit
         regs preserved

        This call is simplar to ImageEntry_Func 32.  These are the valid
        values for r2 on entry:
        r2      meaning
        0       stamp image on next update
        1       stamp image now
        To stamp an image the image's unique identification number should be updated
        to a different value. This value is used to distinguish between different
        discs with the same name and to determine when a given disc has been
        updated. The image's unique identification number is that which should be
        filled in the disc record disc id field when the disc is originally
        identified. This entry's form is similar to that for the ImageEntry for
        consitency's sake. The most likely use is:
        *  When a Backup program wishes to cause a backup of the original to be
        distinguishable from the original it may use the stamp image now form.

        FSEntry_Func 33 (fsfunc_ObjectAtOffset)

        On entry
         r0 = 33
         r1 = pointer to nul-terminated name of an object on the disc of imterest
         r2 = offset into disc
         r3 = pointer to buffer to receive object name
         r4 = buffer length
         r6 = special field

        On exit
         r2 = kind of object found at offset:
                0 if offset is free; beyond end of image; a defect
                1 if offset is allocated but not free, defect or beyond image end
                2 if found an object at the offset and it's the only object
                3 if found an object at the offset and it may share the offset with other objects
        buffer filled in with name of object (r2=2,3) or buffer contents may be corrupted.

        The FS should find out the usage of the given offset within the disc.
        If the offset is free, a defect or outside the disc then r2 should be
        returned with the value 0. If the offset is used, but has no object name
        which corresponds to it (for example the free space map, FAT tables, boot
        block and the such), then a return value of 1 is appropriate. If the offset
        is associated with several objects (files/directories), but cannot be said
        to be associated with one only (for example, the disc may have one large
        section allocated which is used by several files within one directory), then
        the appropriate value to return is 3. If the given offset is associated with
        only one object (such that deleting that object would definitely free the
        given offset), then a return value of 2 should be used. The buffer
        may be corrupted during the search and, if an object is found,
        should contain the path from the disc's root to the object found.
        Note that no '$.' prefix should be filled in. Note also that the first
        path element should have a . prefix, so the whole path filled in would
        read something like:
        .a.b.c.d
        and not:
        a.b.c.d

        FSEntry_Args 10 (fsargs_ImageStampIs)

        On entry
         r0 = 10
         r1 = file handle
         r2 = new image stamp of image

        On exit
         regs preserved

        This FSEntry_Args call is for a MultiFS to tell the host filing
        system when the Id of a given image has changed, and its new value.
        If your filing system does not support the root object being a
        MultiFS image then these calls should be ignored. Otherwise, for
        example in the case of FileCore, these calls should be used to
        maintain the internal note of a disc's Id for the purposes of
        identifying the disc at a later time. These calls are for
        information only and should not require further action other than
        the storing of the passed-in value.

New SWIs
--------

OS_FSControl 35

Register an image filing system with FileSwitch

On entry
 R0 = 35
 R1 = module base address
 R2 = offset of image filing system information block from the module base
 R3 = private word pointer

On exit
 Registers preserved

This call inform FileSwitch of a new image filing system to be added to the
list of those it knows about. The module containing the image filing system
should make this call when it initialises. This call is very similar to
OS_FSControl 12 Add a filing system, except that it refers to an image
filing system.

Image filing system control block:

Image file system information word
Image file system file type
Offset of routine to open files                 ImageEntry_Open
Offset of routine to get bytes                  ImageEntry_GetBytes
Offset of routine to put bytes                  ImageEntry_PutBytes
Offset of routine to control open files         ImageEntry_Args
Offset of routine to close files                ImageEntry_Close
Offset of routine to do whole file operations   ImageEntry_File
Offset of routine to do various FS operations   ImageEntry_Func


In the following descriptions a filename or pathname will always be relative
to the root directory of the supplied image file, will never have any ^s in
them, nor will it have $s, @s, %s \s or &s. When a wildcarded pathname is
specified, only on the final leaf should the operation in question be
applied to all items; earlier wildcarded elements in the path should use the
first match. A "" pathname, when passed to the image file system, indicates,
in the obvious fashion, the root directory in the image file.


Image file system information word:
Bit  Meaning when set
27   Notify image filing system of a flush
All bits are reserved and should be set to 0


Image file system file type:
This word gives the file type number of files which contain images
understood by this image file system.

ImageEntry_Open:
On entry
  R1 = Pointer to filename (null terminated)
  R6 = Image file system handle of image file

On exit
  R0 = file information word
  R1 = Image file system handle for this file
  R2 = buffer size for FileSwitch to use (must be a power of 2 between 64 and 1024)
  R3 = file length
  R4 = space allocated to file (must be a multiple of buffer size)

A handle of 0 means that no file is open. This would be the case if, for
example, a memory allocation failed.

file information word:
Bit  Meaning if set
31   Write permitted to this file
30   Read permitted from this file
All other bits are reserved and should be set to 0


ImageEntry_GetBytes:
On entry:
  R1 = Image file system file handle of file to be read from
  R2 = memory address to put data
  R3 = number of bytes to read
  R4 = file offset to get data from

On exit

The file specified will not be a directory, but may not have read access.
In that latter case, no read access, the read is being requested so that
FileSwitch's buffers may be filled before a write operation which the user
requested. The GetBytes request should be honoured so that when FileSwitch
writes its buffer out the correct, unmodified, data is written as well as
the modified data.

ImageEntry_PutBytes:
On entry:
  R1 = Image file system handle of file to be written to
  R2 = memory address to get data from
  R3 = number of bytes to write
  R4 = file offset to put data to

On exit

The file handle is guaranteed to not be a directory and to have write access
granted when it was opened.


ImageEntry_Args:
ImageEntry_Args 3 Write file extent
On entry:
  R0 = 3
  R1 = Image file system's file handle
  R2 = new file extent
On exit:

This call is used to set the extent of a file prior to it being closed.

ImageEntry_Args 4 Read file allocated size
On entry:
  R0 = 4
  R1 = Image file system's file handle
On exit:
  R2 = size allocated to file by filing system

ImageEntry_Args 6 Notify of a flush
On entry
  R0 = 6
  R1 = Image file system's file handle
On exit:
  R2 = load address of file (or 0)
  R3 = execution address of file (or 0)

This call is used to notify the filing system to flush any modified data
that it is holding in buffers to its image file. The image file should
subsequently be flushed to ensure the flush feeds through eventually to the
medium.

ImageEntry_Args 7 Ensure file size
On entry
  R0 = 7
  R1 = image file system's file handle
  R2 = size of file to ensure
On exit
  R2 = size of file actually ensured

This call is used to ensure the file can be extended to at least the given
size. The image file system need not ensure the extra space is zeroed.

ImageEntry_Args 9 Read file date stamp
On entry
  R0 = 9
  R1 = image file system's file handle
On exit
  R2 = load address of file (or 0)
  R3 = execute address of file (or 0)

This call is used to read the date/time stamp of a given file. (see PRM page
982-983 for details).

ImageEntry_Close:
On entry
  R1 = Image file system's file handle
  R2 = new load address for file
  R3 = new execute address for file
On exit

This call is used to close a file and put a new date/time stamp on it.


ImageEntry_File:
ImageEntry_File 0 Save file
On entry
  r0 = 0
  r1 = pointer to filename (null terminated)
  r2 = load address to associate with file
  r3 = execution address to associate with file
  r4 = start address in memory of data
  r5 = end address in memory plus one
  r6 = Image file system's handle for image file
On exit
  r6 = pointer to a leafname for printing *OPT 1 info

This call works exactly as the FSEntry_File 0 in the PRM works.

ImageEntry_File 1 Write catalogue information
On entry
  R0 = 1
  R1 = pointer to wildcarded filename (nul terminated)
  R2 = new load address for file
  R3 = new execution address for file
  R5 = new attributes for file
  R6 = Image file system's handle for image file
On exit

Write the catalogue information. If the object is a directory and your image
file system cannot write the information then return an error. If the object
does not exist, don't return an error.

ImageEntry_File 5 Read catalogue information
On entry
  R0 = 5
  R1 = pointer to wildcarded pathname (nul terminated)
  R6 = image file system's handle for image file
On exit
  R0 = object type
        0       not found
        1       file
        2       directory
  R2 = load address
  R3 = execution address
  R4 = file length
  R5 = file attributes
  R6 = Image file system's handle for image file

You should return r0=0 if the object specified does not exist, or any of the
directories along its path do not exist.

ImageEntry_File 6 Delete object
On entry
  R0 = 6
  R1 = pointer to filename (nul terminated)
  R6 = Image file system's handle for image file
On exit
  R0 = object type
  R2 = load address
  R3 = execute address
  R4 = file length
  R5 = file attributes

This call deletes an object. Don't bother transfering any data for this
object. The returned values refer to the object deleted. Do not return an
error if the object didn't exist.

ImageEntry_File 7 Create file
On entry
  R0 = 7
  R1 = pointer to filename (nul terminated)
  R2 = load address
  R3 = execution address
  R4 = length of file
  R6 = Image file system's handle for image file
On exit

This call creates a file. Create the file with the given load and execute
address and file length. If a file already exists, replace it with the
created file, unless the original file's access attributes forbid this, in
which case an error should be returned. The new file should have the same
access attributes as the old one, or some default access if the old file
doesn't exist.

ImageEntry_File 8 Create directory
On entry
  R0 = 8
  R1 = pointer to filename (nul terminated)
  R2 = load address
  R3 = execute address
  R6 = Image file system's handle for image file
On exit

This call creates a directory. If directories don't support load and execute
addresses (which will only be of the directory type/datestamp form) then no
error should be returned. If the directory already exists, try renaming it
(the case of the letters might have changed), but don't return an error if
it fails. If the create fails return an error.

ImageEntry_File 10 (fsfile_ReadBlockSize)

On entry
 r0 = 10
 r1 = file name
 r6 = special field

On exit
 r2 = natural block size of the file (in bytes)


ImageEntry_Func:
ImageEntry_Func 8 Rename object
On entry
  R0 = 8
  R1 = pointer to name of object to be renamed (nul terminated)
  R2 = pointer to name of new name for object (nul terminated)
  R6 = Image file system's handle for image file

This call renames an object (file OR directory) within a given image file.
If, in a *rename, the two objects are on different image files, then the
rename will fail.

ImageEntry_Func 14 Read directory entries
On entry
  R0 = 14
  R1 = Pointer to wildcarded directory name
  R2 = memory address to put data
  R3 = number of object names to read
  R4 = offset of first item to read in directory (0 for start of directory)
  R5 = buffer length
  R6 = Image file system's handle for image file
On exit
  R3 = number of records read
  R4 = offset of next item to read in directory (-1 if end)

The leaf names of entries should be placed in the supplied buffer, as for
FSEntry_Func 14.

ImageEntry_Func 15 Read directory entries and information
On entry
  R0 = 15
  R1 = Pointer to wildcarded directory name
  R2 = memory address to put data
  R3 = number of object names to read
  R4 = offset of first item to read in directory (0 for start of directory)
  R5 = buffer length
  R6 = Image file system's handle for image file
On exit
  R3 = number of records read
  R4 = offset of next item to read in directory (-1 if end)

The leaf names of entries and their file information should be placed in the
supplied buffer, as for FSEntry_Func 15.

ImageEntry_Func 21 Notification of new image file
On entry
  R0 = 21
  R1 = FileSwitch file handle of file
  R2 = Buffer size for file, or 0 if not known.
         This should be treated as a hint to the sector size.
On exit
  R1 = Image file system file handle of image file

This notifies an image filing system that FileSwitch would like it to handle
this image file. This entry gives the image filing system a chance to set up
internal structures so that data could be cached or buffered from the image.
All future requests FileSwitch makes of the image file system will quote the
returned image file's image file system handle when appropriate. The image
should be flagged internally as 'needs a new unique identification number
when updated', and when it is updated its unique identification number
should be updated. Whenever this number is updated the host filing system
should be informed of its new value using OSArgs_ImageStampIs - this is
important, because otherwise the host filing system will lose track of which
disc is which.

ImageEntry_Func 22 Notification of image file about to be closed
On entry
  R0 = 22
  R1 = Image file system's file handle of image file
On exit

All files will have been closed for you before this call is made. You should
save any buffered data for this image file before returning, and discard
any cached data.

ImageEntry_Func 25 (fsfunc_DefectList)

On entry
 r0 = 25
 r1 = pointer to nul-terminated name of image
 r2 = start of buffer in memory
 r5 = buffer length
 r6 = Image file system's handle for image file

On exit
 r0-r6 unchanged

This entry will fill the supplied buffer with the byte offsets to the start of
the defects. The list will be terminated by a &20000000 value. It is
an error for the specified image to not be the root object in an
image (eg it is an error to map out a defect from
adfs::HardDisc4.$.fred, but not an error from mapping it out from
adfs::HardDisc4.$).

ImageEntry_Func 26 (fsfunc_AddDefect)

On entry
 r0 = 26
 r1 = pointer to nul-terminate name of image
 r2 = byte offset to start of defect
 r6 = Image file system's handle for image file

On exit
 r0-r2,r6 preserved

This SWI will map out the specified defect from the specified image.
It is an error for the specified image to not be the root object in
an image (eg it is an error to map out a defect from
adfs::HardDisc4.$.fred, but not an error from mapping it out from
adfs::HardDisc4.$). If the defect cannot be mapped out then an error
should be returned.

ImageEntry_Func 27 (fsfunc_ReadBootOption)

On entry
 r0 = 27
 r1 = pointer to nul-terminated name of object on thing whose boot option is to be read
 r6 = Image file system's handle for image file

On exit
 r0-r1,r6 preserved
 r2 = boot option (as in *Opt4,n)

ImageEntry_Func 28 (fsfunc_WriteBootOption)

On entry
 r0 = 28
 r1 = pointer to nul-terminated name of object on thing whose boot option is to be written
 r2 = new boot option
 r6 = Image file system's handle for image file

On exit
 r0-r2,r6 preserved

ImageEntry_Func 29 (fsfunc_UsedSpaceMap)

On entry
 r0 = 29
 r2 = buffer for map (pre-filled with 0s)
 r5 = size of buffer
 r6 = Image file system's handle for image file

On exit
 regs preserved

Fill in 1s in the used space map for parts of the image which are neither
free space nor bad block areas. In other words the buffer should end up with
1s where there are used parts of the disc. Each bit in the buffer
corresponds with a BlockSize unit of the image.

ImageEntry_Func 30 (fsfunc_ReadFreeSpace)

On entry
 r0 = 30
 r6 = Image file system's handle for image file

On exit
  r0 = free space
  r1 = biggest object creatable
  r2 = disc size

Does the obvious.

ImageEntry_Func 31 (fsfunc_NameDisc)

On entry
 r0 = 31
 r2 = new name of disc (nul-terminated)
 r6 = Image file system's handle for image file

On exit
  regs preserved

Does the obvious 

ImageEntry_Func 32 (fsfunc_StampImage)

On entry
 r0 = 32
 r2 = type of image stamping to take place
 r6 = Image file system's handle for image file

On exit
 regs preserved

This entry is used for FileCore to communicate with the MultiFS for control
of and management of the disc Id of a given image. These are the valid
values for r2 on entry:
r2      meaning
0       stamp image on next update
1       stamp image now
To stamp an image the image's unique identification number should be updated
to a different value. This value is used to distinguish between different
discs with the same name and to determine when a given disc has been
updated. The image's unique identification number is that which should be
filled in the disc record disc id field when the disc is originally
identified. The kind of uses expected for these calls are:
*  When FileCore notices that a given disc may have been removed from the
drive it will call the MultiFS (via FileSwitch) with the 'stamp image on
next update' call. This informs the MultiFS that when it next changes
something in that image that it should also explicitly (if possible) change
the unique Id number. The reason this is done is so that if another machine
saw the disc whilst it was removed then that other machine will be given a
clue that the disc has since been changed by the Id number changing - the
other machine will probably discard any cached data it has as none of it
could be trusted to still be accurate. Once the Id has been updated once
there is no further need to update it on an update unless, of course, a
further 'stamp image on next update' occurs.
*  When FileCore is explicitly requested to stamp a disc it will use the
'stamp image now' call to get the message through to the relevant MultiFS.
*  When a Backup program wishes to cause a backup of the original to be
distinguishable from the original it may use the stamp image now form.

ImageEntry_Func 33 (fsfunc_ObjectAtOffset)

On entry
 r0 = 33
 r2 = offset into image
 r3 = pointer to buffer to receive object name
 r4 = buffer length
 r6 = Image file system's handle for image file

On exit
 r2 = kind of object found at offset:
        0 if offset is free; beyond end of image; a defect
        1 if offset is allocated but not free, defect or beyond image end
        2 if found an object at the offset and it's the only object
        3 if found an object at the offset and it may share the offset with other objects
buffer filled in with name of object (r2=2,3) or buffer contents may be corrupted.

The MultiFS should find out the usage of the given offset within the image.
If the offset is free, a defect or outside the image then r2 should be
returned with the value 0. If the offset is used, but has no object name
which corresponds to it (for example the free space map, FAT tables, boot
block and the such), then a return value of 1 is appropriate. If the offset
is associated with several objects (files/directories), but cannot be said
to be associated with one only (for example, the image may have one large
section allocated which is used by several files within one directory), then
the appropriate value to return is 3. If the given offset is associated with
only one object (such that deleting that object would definitely free the
given offset), then a return value of 2 should be used. The buffer may be
corrupted during the search and, if an object is found, should contain the
path from the image's root to the object found. Note also that the first
path element should have a . prefix, so the whole path filled in would
read something like:
.a.b.c.d
and not:
a.b.c.d


OS_FSControl 36

De register an image filing system with FileSwitch.

On entry
 r0 = 36
 r1 = image file system file type
On exit

This call removes the given image filing system from the list of those which
FileSwitch knows about.

OS_FSControl 37 (FSControl_CanonicalisePath)

On entry
 r0 = 37
 r1 = Pointer to path to be canonicalised
 r2 = Pointer to buffer to be filled in
 r3 = Pointer to system variable name of path to use, or 0 if none
 r4 = Pointer to default path to use if no system variable is specified
        or if that variable doesn't exist, or 0 if no path is the default
 r5 = Buffer length

On exit
 Buffer filled in with 0-terminated canonicalised name, and
 r5 = number of spare bytes in the buffer after and including
        the 0 terminator. If the buffer would have overflowed,
        then this will be taken to negative the overflow, but
        the overflow won't actually have happened. This
        provides a machanism for finding out how much buffer
        is needed. Note that a value of '0' in r5 means the buffer
        overflowed by 1 byte (the \0 terminator).

This may be used as a two-pass process:
  Pass 1:
    In:
      r0 = 37
      r1 = Pointer to path
      r2 = 0
      r5 = 0
  Out:
      r5 = -(length of canonicalised path)
 Pass 2:
  Claim buffer of the right size (1-r5, not just -r5 as a space for the terminator is needed)
    In:
      r0 = 37
      r1 = Pointer to path
      r2 = Pointer to claimed buffer
      r5 = size of claimed buffer
    Out:
      r5 should be 0, but check to make sure!

v) Given a file handle, fileswitch will return the name of the file.

OS_Args 7 (OSArgs_ReadPath)
On entry
 r0 = 7
 r1 = file handle
 r2 = Pointer to buffer to be filled in
 r5 = Buffer length
On exit
 Buffer filled in with 0-terminated canonicalised name, and
 r5 = number of spare bytes in the buffer after and including the 0
        terminator.
        If the buffer would have overflowed, then this will be
        taken to negative the overflow, but the overflow won't
        actually have happened. This provides a machanism for
        finding out how much buffer is needed. Supply r5=0 (no buffer) and
        the buffer size required will be 1-r5.

This call can be used in the same way as OS_FSControl 37.

vi) FileSwitch now processes the conversion of file info into filetype
information.

OS_FSControl 38 (FSControl_InfoToFileType)
On entry
 r0 = 38
 r1 = a pointer to the object's name
 r2 = object's load address
 r3 = object's execute address
 r4 = object's length
 r5 = objects's attributes
 r6 = object's type (file/directory)
On exit
 r2 = object's type:
        Special values:
        -1      untyped
        &1000   directory
        &2000   application directory (directory whose name starts with a '!').

OS_File 20-23 (OSFile_ReadWithType, _ReadWithTypePath, _ReadWithTypePathVar
                and _ReadWithTypeNoPath)

On Entry
 r0 = 20, 21, 22 or 23
 r1 = Pointer to name of object
On exit
 r0 = object's type
 r1 unchanged
 r2 = Object's load address or top word of date stamp (Top three bytes 000000)
 r3 = Object's execute address or bottom word of date stamp
 r4 = Object's length
 r5 = object's attributes
 r6 = Object's type:
        Special values:
        -1      untyped         (r2, r3 are load and execute address)
        &1000   directory
        &2000   application directory (directory whose name starts with a '!').

OS_GBPB 12 (OSGBPB_ReadDirEntriesFileType)

On entry
 r0 = 12
 r1 = pointer to directory name
 r2 = start address of data in memory (word aligned)
 r3 = number of names to read from directory
 r4 = offset of first item to read from directory (0 for start)
 r5 = buffer length
 r6 = Pointer to (Wildcarded) name to match

On exit
 r0-r2 unchanged
 r3 = number of objects read
 r4 = offset of next item to read
 r5, r6 unchanged

This call is similar in function to OS_GBPB 10, except the buffer is filled
in with entries like this:

Offset  Contents
0       Load address or high word of date stamp (Top three bytes 000000)
4       Execute address of low word of date stamp
8       Length
12      File attributes
16      Object type
20      Object's file type (as for OS_File 20-23)
24      Object's name (null terminated)


OS_FSControl 41 (FSControl_DefectList)

On entry
 r0 = 41
 r1 = pointer to nul-terminated name of image
 r2 = start of buffer in memory
 r5 = buffer length

On exit
 r0-r5 unchanged

This SWI will fill the supplied buffer with the byte offsets to the start of
the defects. The list will be terminated by a &20000000 value.

OS_FSControl 42 (FSControl_AddDefect)

On entry
 r0 = 42
 r1 = pointer to nul-terminate name of image
 r2 = byte offset to start of defect

On exit
 r0-r2 preserved

This SWI will map out the specified defect from the specified image.

OS_File 24 (OSFile_ReadBlockSize)

On entry
 r0 = 24
 r1 = file name

On exit
 r2 = natural block size of the file

OS_FSControl 46 (FSControl_UsedSpaceMap)

On entry
 r0 = 46
 r1 = pointer to nul-terminated name of image
 r2 = start of buffer in memory
 r5 = buffer length

On exit
 r0-r5 preserved

The supplied buffer will be filled with 0 bits for unused blocks and 1 bits
for used blocks. The buffer will be filled to its limit or the file's limit,
whichever is less. The 'perfect' size of the buffer can be calculated from
the file's size and its block size. For non-MultiFS files the buffer will be
filled with 1s. The correspondance of the file to the buffer is 1 bit to 1
block. The least significant bit (bit 0) in a byte comes before the most
significant bit.

OS_FSControl 47 (FSControl_ReadBootOption)

On entry
 r0 = 47
 r1 = pointer to nul-terminated name of object on thing whose boot option is to be read

On exit
 r0-r1 preserved
 r2 = boot option (as in *Opt4,n)

OS_FSControl 48 (FSControl_WriteBootOption)

On entry
 r0 = 48
 r1 = pointer to nul-terminated name of object on thing whose boot option is to be written
 r2 = new boot option

On exit
 r0-r2 preserved

OS_FSControl 49 (FSControl_ReadFreeSpace)

On entry
 r0 = 49
 r1 = pointer to nul-terminated name of object on thing whose free space is to be read

On exit
 r0 = free space
 r1 = biggest creatable object
 r2 = disc size

Does the obvious.

OS_FSControl 50 (FSControl_NameDisc)

On entry
 r0 = 50
 r1 = pointer to nul-terminated name of object on disc whose name is to be changed
 r2 = new name of disc

On exit
  regs preserved

Does the obvious.

OS_FSControl 51 (FSControl_StampImage)

On entry
 r0 = 51
 r1 = pointer to nul-terminated name of object which is to be image-stamped
 r2 = sub-reason:
        0       stamp when updated
        1       stamp now

On exit
 regs preserved

This call is provided to allow communication between a handler of discs (eg
FileCore) and a MultiFS which is interpreting a disc (eg DOSFS). This call
is made by FileCore to DOSFS to inform it that it should update the disc's
unique identification number when the disc is next updated (r2=0) or now
(r2=1). Under normal circumstances a user need never make use of this call.

OS_FSControl 52 (FSControl_ObjectAtOffset)

On entry
 r0 = 52
 r1 = pointer to nul-terminated name of object of interest
 r2 = offset into disc or image
 r3 = pointer to buffer to receive object name
 r4 = buffer length

On exit
 r2 = kind of object found at offset:
        0 if offset is free; beyond end of image; a defect
        1 if offset is allocated but not free, defect or beyond image end
        2 if found an object at the offset and it's the only object
        3 if found an object at the offset and it may share the offset with other objects
buffer filled in with name of object (r2=2,3) or buffer contents may be corrupted.

This call can be used to find out what object uses a particular offset
within an image. The image searched is the deepest image, eg if the path
supplied was:
$.pc.amiga.atari.a.b.c
where pc is a DOS disc image, amiga was an amiga image and atari an atari
disc image, then the image searched would be:
$.pc.amiga.atari
The return values reflect what usage that the given offset within that image
has. The buffer will be filled with the full path of the found object.

OS_Args 8 (OSArgs_ImageStampIs)

On entry
 r0 = 8
 r1 = file handle
 r2 = new image stamp

On exit
 regs preserved

This call is provided to allow communication between a handler of discs (eg
FileCore( and a MultiFS which is interpreting a disc (eg DOSFS). This call
is made by DOSFS to tell FileCore when it has changed the disc's unique
identification number and its new value. FileCore's only action would be to
store the new image stamp against the record for that disc so that that disc
may be identified at a later time.

OS_FSControl 53 (FSControl_SetDir)

On entry
 r0 = 53
 r1 = pointer to rest of path
 r2 = which directory to set
 r3 = filing system
 r6 = pointer to special field

On exit
 registers preserved

This call allows a filing system to explicitly tell FileSwitch to set the
specified directory to the given path without FileSwitch performing any form
of verification on the path provided.
 r1 = pointer to rest of path
This must be provided. This is the string which is the canonical path from
the disc (if present) to the leaf which is the directory. It must not have
wildcards in it, nor may it have any GSTransable bits to it. The string must
be 0-terminated. It must have a root directory of some sort (ie $, % or &
must be present at the right place). For example *Mount on ADFS may set
the library to ":HardDisc4.$.Library" and *Logon on NetFS may set the
URD to ":Arf.&".
If r1 is 0 on entry then the releavnt directory will be put into the "Unset"
state.
 r2 = which directory to set
This tells FileSwitch which of the settable directories should be set:
Value   Directory
0       @ - currently selected directory
1       \ - previously selected directory
2       & - user root directory
3       % - library
Other values are illegal.
 r3 = filing system
This must be provided and points to the name of the filing system,
0-terminated.
 r6 = pointer to special field
This is optional. If not present set r3=0. The special field must point at
the textual part of the special field, after any # prefix that may have been
present. The special field is terminated by a 0 or a '.'. The special field
must not contain any wildcards or GSTransable bits.


OS_FSControl 54 (FSControl_ReadDir)

On entry
 r0 = 54
 r1 = pointer to buffer
 r2 = which directory to read
 r3 = filing system
 r5 = size of buffer

On exit
 r1 = 0 if directory unset, else points to start of rest of path if managed
        to be placed into buffer.
 r5 reduced by length total size of directory string including terminator
 r6 = pointer to special field or 0 if not present

This call is the reverse of FSControl_SetDir. It is expected that this call
will be used twice, the first time to get the buffer length, the second time
to fill the buffer. The buffer will have the special field and the rest of
the path placed into it. The values in r1 and r6 are suitable for submission
to FSControl_SetDir.
